home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 2 / Amiga Tools 2.iso / tools / packer / xpkarchive / xpkarchive.doc < prev    next >
Text File  |  1995-03-09  |  30KB  |  1,008 lines
  1. TABLE OF CONTENTS
  2.  
  3. xpkarchive.library/XarAddFileA
  4. xpkarchive.library/XarCloseArchive
  5. xpkarchive.library/XarCopyFileA
  6. xpkarchive.library/XarExamine
  7. xpkarchive.library/XarExtractFileA
  8. xpkarchive.library/XarFindFileA
  9. xpkarchive.library/XarGetFileData
  10. xpkarchive.library/XarGetFileIndex
  11. xpkarchive.library/XarGetFileName
  12. xpkarchive.library/XarGetFileNote
  13. xpkarchive.library/XarGetFileSize
  14. xpkarchive.library/XarGetLock
  15. xpkarchive.library/XarGetType
  16. xpkarchive.library/XarIsXpkArchive
  17. xpkarchive.library/XarModifyFileDataA
  18. xpkarchive.library/XarNextGenerationA
  19. xpkarchive.library/XarNextLock
  20. xpkarchive.library/XarOpenArchiveA
  21. xpkarchive.library/XarPrevLock
  22. xpkarchive.library/XarRenameFileA
  23. xpkarchive.library/XarSetFileNoteA
  24. xpkarchive.library/--tags--
  25. xpkarchive.library/--error--
  26. xpkarchive.library/--generations--
  27. xpkarchive.library/--BUGS--
  28.  
  29. xpkarchive.library/XarAddFileA                xpkarchive.library/XarAddFileA
  30.  
  31.     NAME
  32.         XarAddFile
  33.  
  34.     SYNOPSIS
  35.         arclock = XarAddFileA( tags )
  36.         D0                      A0
  37.  
  38.         XarLock * XarAddFileA(struct TagItem *)
  39.  
  40.     FUNCTION
  41.         XarAddFileA() adds a file to the archive using XPK to compress the
  42.         file that has to be added to the archive. XarAddFileA() uses the
  43.         same tags for compression as XPK plus some additional tags. In fact
  44.         the XPK-tags are just passed on to XpkPack(). Since the ouput-tags
  45.         are already set by the xpkarchive.library you must not supply these
  46.         tags. The function internally calls XarNextGeneration() to prevent
  47.         duplicate filenames with the same generationnumber by default.
  48.         You can suppress this behaviour by using the XAR_AutoNextGen tag.
  49.     NOTE: a4 is preserved, therefore hooks called by this function need not
  50.         use __saveds. See xpk/--progress-- for further information.
  51.  
  52.     TAGS
  53.         supported tags:
  54.             XAR_Error
  55.             XAR_InName
  56.             XAR_Archive
  57.             XAR_FileName
  58.             XAR_Generation
  59.             XAR_FileNote
  60.             XAR_TimeDay
  61.             XAR_TimeMonth
  62.             XAR_TimeYear
  63.             XAR_TimeHour
  64.             XAR_TimeMin
  65.             XAR_TimeSec
  66.             XAR_DateStamp
  67.             XAR_CurrentTime
  68.             XAR_CRC
  69.             XAR_Protection
  70.             XAR_InLen
  71.             XAR_AutoNextGen
  72.  
  73.             all XPK-Tags, that are supported by XpkPack(),
  74.             without output Tags
  75.  
  76.     INPUT
  77.         tags    - Pointer to an array of struct TagItem. See xpkarchive/tags
  78.  
  79.     RESULT
  80.         arclock - the ArcLock of the added file or NULL, if there was an
  81.                   error
  82.  
  83.     SEE ALSO
  84.         XarOpenArchive(),XarExtractFileA(),XarNextGeneration(),
  85.         xpkarchive/tags
  86.  
  87.  
  88. xpkarchive.library/XarCloseArchive        xpkarchive.library/XarCloseArchive
  89.  
  90.     NAME
  91.         XarCloseArchive
  92.  
  93.     SYNOPSIS
  94.         err = XarCloseArchive( arc )
  95.         D0                  A0
  96.  
  97.         LONG  XarCloseArchive(XarHandle *)
  98.  
  99.     FUNCTION
  100.         Closes Archive that was opened with XarOpenArchiveA().
  101.  
  102.     INPUT
  103.         arc     - The ArcHandle obtained from XarOpenArchiveA()
  104.  
  105.     RESULT
  106.         err     - Xar error code
  107.  
  108.     SEE ALSO
  109.         XarOpenArchiveA()
  110.  
  111.  
  112. xpkarchive.library/XarCopyFileA              xpkarchive.library/XarCopyFileA
  113.  
  114.     NAME
  115.         XarCopyFileA
  116.     SYNOPSIS
  117.         arclock=XarCopyFileA( tags )
  118.         D0                     A0
  119.  
  120.         XarLock *XarCopyFileA(struct TagItem *)
  121.  
  122.     FUNCTION
  123.         With XarCopyFileA() you can copy files between to archives without
  124.         decompressing and newly compressing them. For this the two archives
  125.         must be of the same type. You can determine the type of an archive
  126.         using XarGetType(). The type of standard XpkArchive-archives is
  127.         "XPKArchive". The function internally calls XarNextGeneration()
  128.         to prevent duplicate filenames by default. You can suppress this
  129.         by using the tag XAR_AutoNextGen.
  130.  
  131.     TAGS
  132.         supported tags:
  133.             XAR_Error
  134.             XAR_ArcLock
  135.             XAR_Archive
  136.             XAR_DestArchive
  137.             XAR_AutoNextGen
  138.             XAR_NewName
  139.             XAR_FileNote
  140.             XAR_NewGeneration
  141.             XAR_ArcLock
  142.             XAR_Archive
  143.             XAR_FileIndex
  144.             XAR_FileName
  145.             XAR_Generation
  146.  
  147.     INPUT
  148.         tags    - Pointer to an array of struct TagItem. See xpkarchive/tags
  149.  
  150.     RESULT
  151.         arclock - The arclock of the file in the destination archive or
  152.                   NULL if an error happened.
  153.  
  154.     SEE ALSO
  155.         XarOpenArchiveA(),XarNextGeneration(),xpkarchive/tags
  156.  
  157.  
  158. xpkarchive.library/XarExamine                  xpkarchive.library/XarExamine
  159.  
  160.     NAME
  161.         XarExamine()
  162.  
  163.     SYNOPSIS
  164.         err = XarExamine( xarlock , xfib )
  165.         D0                  A0       A1
  166.  
  167.         LONG XarExamine( XarLock *, struct XpkFib * )
  168.  
  169.     FUNCTION
  170.         XarExamine() is the xpkarchive.library version of XpkExamine().
  171.         With this function it is possible to get additional informations
  172.         about files in the archive. You cannot use this function on archives
  173.         which are no xpk-archives.
  174.  
  175.     INPUT
  176.         xarlock - xarlock obtained by XarGetLock(),XarNextLock(),
  177.                   XarPrevLock() or XarFindFileA()
  178.         xfib    - pointer to an xpk-fib structure
  179.  
  180.     RESULT
  181.         err - Error code
  182.  
  183.     SEE ALSO
  184.         XarGetLock(),XarNextLock(),XarPrevLock(),XarFindFileA()
  185.  
  186.  
  187. xpkarchive.library/XarExtractFileA        xpkarchive.library/XarExtractFileA
  188.  
  189.     NAME
  190.         XarExtractFileA
  191.  
  192.     SYNOPSIS
  193.         err = XarExtractFileA( tags )
  194.         D0                      A0
  195.  
  196.         LONG XarExtractFileA(struct TagItem *)
  197.  
  198.     FUNCTION
  199.         This function is used to extract files from an archive and decompress
  200.         them. Just like XarAddFile() it uses the XPK tags for uncompression
  201.         plus some additional tags. These tags are passed on to XpkUnPack().
  202.         Therefore you must not supply XPK_In - tags.
  203.     NOTE: a4 is preserved, therefore hooks called by this function need not
  204.         use __saveds. See xpk/--progress-- for further information.
  205.  
  206.     TAGS
  207.         supported tags:
  208.             XAR_Error
  209.             XAR_ArcLock
  210.             XAR_Archive
  211.             XAR_FileIndex
  212.             XAR_FileName
  213.             XAR_Generation
  214.  
  215.             all XPK-Tags, that are supported by XpkUnpack(),
  216.             without input Tags
  217.  
  218.     INPUT
  219.         tags    - Pointer to an array of struct TagItem. See xpkarchive/tags
  220.  
  221.     RESULT
  222.         err - Error code
  223.  
  224.     SEE ALSO
  225.         XarAddFile(),xpkarchive/tags
  226.  
  227.  
  228. xpkarchive.library/XarFindFileA              xpkarchive.library/XarFindFileA
  229.  
  230.     NAME
  231.         XarFindFileA
  232.  
  233.     SYNOPSIS
  234.         arclock = XarFindFileA( tags )
  235.         D0                       A0
  236.  
  237.         XarLock *XarFindFileA(struct TagItem *)
  238.  
  239.     FUNCTION
  240.         Find the arclock to a given filename and generation number or
  241.         fileindex number.
  242.  
  243.     TAGS
  244.         supported tags:
  245.             XAR_ArcLock
  246.             XAR_Archive
  247.             XAR_FileIndex
  248.             XAR_FileName
  249.             XAR_Generation
  250.  
  251.     INPUT
  252.         tags    - Pointer to an array of struct TagItem. See xpkarchive/tags
  253.  
  254.     RESULT
  255.         arclock - the arclock of the file or NULL
  256.  
  257.     SEE ALSO
  258.         XarNextLock(),XarPrevLock(),xpkarchive/tags
  259.  
  260.  
  261. xpkarchive.library/XarGetFileData          xpkarchive.library/XarGetFileData
  262.  
  263.     NAME
  264.         XarGetFileData
  265.  
  266.     SYNOPSIS
  267.         fdata = XarGetFileData( arclock )
  268.         D0                        A0
  269.  
  270.         struct FileData *XarGetFileData(XarLock *)
  271.  
  272.     FUNCTION
  273.         With this function you can get information about the file stored in
  274.         the archive. NOTE: the size of the compressed file is NOT stored in
  275.         fdata. You can get the size of the compressed file using the function
  276.         XarGetFileSize().
  277.  
  278.     INPUT
  279.         arclock - the arclock of an file in the archive. You can find the
  280.                   arclock of an file using XarFindFileA() or XarGetLock()/
  281.                   XarNextLock()/XarPrevLock()
  282.  
  283.     RESULT
  284.         fdata   - a pointer to struct FileData:
  285.  
  286.                   struct FileData {
  287.                      UBYTE CHKSum;    // Checksum cannot be modified
  288.                      UBYTE Method;    // Compression Method: XPK_COMPRESSION
  289.                      UBYTE Version;    // Version of then xpkmaster.library
  290.                      UBYTE Generation; // Generation
  291.                      USHORT SysID;     // System ID for Amiga: "AM"
  292.                      ULONG Filesize;   // Size of the uncompressed File
  293.                      struct Time Time; // Date of the File
  294.                      USHORT CRC;       // user-definable CRC-Checksum
  295.                      ULONG Protection; // FileProtection Flags
  296.                   };
  297.  
  298.  
  299.  
  300.     SEE ALSO
  301.         XarFindFileA(),XarGetLock(),XarNextLock(),XarPrevLock(),xpkarchive.h,
  302.         XarGetFileSize()
  303.  
  304.  
  305. xpkarchive.library/XarGetFileIndex        xpkarchive.library/XarGetFileIndex
  306.  
  307.     NAME
  308.         XarGetFileIndex
  309.  
  310.     SYNOPSIS
  311.         index = XarGetFileIndex( arclock )
  312.          D0                        A0
  313.  
  314.         ULONG XarGetFileIndex(XarLock *)
  315.  
  316.     FUNCTION
  317.         Evaluates the position of the file in the archive.
  318.  
  319.     INPUT
  320.         arclock - the arclock of an file in the archive. You can find the
  321.                   arclock of an file using XarFindFileA() or XarGetLock()/
  322.                   XarNextLock()/XarPrevLock()
  323.  
  324.     RESULT
  325.         index   - the index of the file in the archive
  326.  
  327.     SEE ALSO
  328.         XarFindFileA(),XarGetLock(),XarNextLock(),XarPrevLock()
  329.  
  330.  
  331. xpkarchive.library/XarGetFileName          xpkarchive.library/XarGetFileName
  332.  
  333.     NAME
  334.         XarGetFileName
  335.  
  336.     SYNOPSIS
  337.         filename = XarGetFileName( arclock )
  338.            D0                        A0
  339.  
  340.         UBYTE *XarGetFileName(XarLock *)
  341.  
  342.     FUNCTION
  343.         Determines the filename of the file, that is identified by arclock.
  344.  
  345.     INPUT
  346.         arclock - the arclock of an file in the archive. You can find the
  347.                   arclock of an file using XarGetLock()/XarNextLock()/
  348.                   XarPrevLock()
  349.  
  350.     RESULT
  351.         filename - the filename
  352.     SEE ALSO
  353.         XarGetLock(),XarNextLock(),XarPrevLock()
  354.  
  355.  
  356. xpkarchive.library/XarGetFileNote          xpkarchive.library/XarGetFileNote
  357.  
  358.     NAME
  359.         XarGetFileNote
  360.  
  361.     SYNOPSIS
  362.         filenote = XarGetFileNote( arclock )
  363.            D0                        A0
  364.  
  365.         UBYTE *XarGetFileNote(XarLock *)
  366.  
  367.     FUNCTION
  368.         Determines the filename of the file, that is identified by arclock.
  369.  
  370.     INPUT
  371.         arclock - the arclock of an file in the archive. You can find the
  372.                   arclock of an file using XarGetLock()/XarNextLock()/
  373.                   XarPrevLock()
  374.  
  375.     RESULT
  376.         filenote - the filenote of the file
  377.     SEE ALSO
  378.         XarGetLock(),XarNextLock(),XarPrevLock()
  379.  
  380.  
  381. xpkarchive.library/XarGetFileSize          xpkarchive.library/XarGetFileSize
  382.  
  383.     NAME
  384.         XarGetFileSize
  385.     SYNOPSIS
  386.         filesize = XarGetFileSize( arclock )
  387.            D0                        A0
  388.  
  389.         ULONG XarGetFileSize(XarLock *)
  390.  
  391.     FUNCTION
  392.         Determines the compressed size of the file, that is identified by
  393.         arclock.
  394.  
  395.     INPUT
  396.         arclock - the arclock of an file in the archive. You can find the
  397.                   arclock of an file using XarGetLock()/XarNextLock()/
  398.                   XarPrevLock()
  399.  
  400.     RESULT
  401.         filesize - the compressed size of the file
  402.  
  403.     SEE ALSO
  404.         XarGetLock(),XarNextLock(),XarPrevLock()
  405.  
  406.  
  407. xpkarchive.library/XarGetLock                  xpkarchive.library/XarGetLock
  408.  
  409.     NAME
  410.         XarGetLock
  411.     SYNOPSIS
  412.         arclock = XarGetLock( arc )
  413.           D0                  A0
  414.  
  415.  
  416.         XarLock * XarGetLock( XarHandle *)
  417.  
  418.     FUNCTION
  419.         This function gets the first entry of the contents list of the
  420.         archive. The arclock returned by this function can be used to get
  421.         further information of the file or to get the next or previous
  422.         entry in the file using XarNextLock() or XarPrevLock().
  423.  
  424.     INPUT
  425.         arc - The archandle returned by XarOpenArchiveA()
  426.  
  427.     RESULT
  428.         arclock - the identifier of a file in the archive, or NULL if the
  429.         archive is empty.
  430.  
  431.     SEE ALSO
  432.         XarNextLock(), XarPrevLock() ,XarOpenArchiveA()
  433.  
  434.  
  435. xpkarchive.library/XarGetType                  xpkarchive.library/XarGetType
  436.  
  437.     NAME
  438.         XarGetType
  439.  
  440.     SYNOPSIS
  441.         type = XarGetType( arc )
  442.          D0                A0
  443.  
  444.         UBYTE * XarGetType( XarHandle * )
  445.  
  446.     FUNCTION
  447.         The type of an archive gives a hint, with which packer it was
  448.         created. The archive that was created with xpkarchive.library have
  449.         the type "XPKArchive". With the function XarGetType() it is possible
  450.         to determine this type of the archive.
  451.         NOTE: Archives of an other type can NOT be modified. No files can be
  452.         extraced from these archives. This behaviour may change in the
  453.         future when there will be xpksublibs, that can handle other types
  454.         of archives, e.g. archives that were created with lha or zoo.
  455.  
  456.     INPUT
  457.         arc - The archandle returned by XarOpenArchiveA()
  458.  
  459.     RESULT
  460.         type - The type of the archive as a null-terminated string.
  461.  
  462.     SEE ALSO
  463.         XarOpenArchiveA()
  464.  
  465.  
  466. xpkarchive.library/XarIsXpkArchive        xpkarchive.library/XarIsXpkArchive
  467.  
  468.     NAME
  469.         XarIsXpkArchive
  470.  
  471.     SYNOPSIS
  472.         bool = XarIsXpkArchive( arc )
  473.          D0                      A0
  474.  
  475.         UBYTE  XarGetType( XarHandle * )
  476.  
  477.     FUNCTION
  478.         Test if an archive is an xpk-archive.
  479.         NOTE: Archives that are no xpkarchives can NOT be modified. No files
  480.         can be extraced from these archives. This behaviour may change in
  481.         the future when there will be xpksublibs, that can handle other
  482.         types of archives, e.g. archives that were created with lha or zoo.
  483.  
  484.     INPUT
  485.         arc - The xarhandle returned by XarOpenArchiveA()
  486.  
  487.     RESULT
  488.         bool - 0 if this is no xpk-archive
  489.  
  490.     SEE ALSO
  491.         XarOpenArchiveA()
  492.  
  493.  
  494. xpkarchive.library/XarModifyFileDataA  xpkarchive.library/XarModifyFileDataA
  495.  
  496.     NAME
  497.         XarModifyFileDataA()
  498.  
  499.     SYNOPSIS
  500.         err = XarModifyFileDataA( tags )
  501.         D0                         A0
  502.  
  503.         LONG XarModifyFileDataA(struct TagItem *)
  504.  
  505.     FUNCTION
  506.         This function is used to modify entries in the FileData structure,
  507.         that is bound to every.
  508.         NOTE: it is not possible to change some fields in the FileData
  509.               structure:
  510.  
  511.                     FileSize,CHKSum
  512.  
  513.     TAGS
  514.         supported tags:
  515.             XAR_Error
  516.             XAR_ArcLock
  517.             XAR_Archive
  518.             XAR_FileIndex
  519.             XAR_FileName
  520.             XAR_Generation
  521.             XAR_TimeDay
  522.             XAR_TimeMonth
  523.             XAR_TimeYear
  524.             XAR_TimeHour
  525.             XAR_TimeMin
  526.             XAR_TimeSec
  527.             XAR_DateStamp
  528.             XAR_CRC
  529.             XAR_Protection
  530.             XAR_NewGeneration
  531.  
  532.     INPUT
  533.         tags    - Pointer to an array of struct TagItem. See xpkarchive/tags
  534.  
  535.     RESULT
  536.         err - Error code
  537.  
  538.     SEE ALSO
  539.         XarGetFileData(),xpkarchive/tags
  540.  
  541.  
  542. xpkarchive.library/XarNextGenerationA  xpkarchive.library/XarNextGenerationA
  543.  
  544.     NAME
  545.         XarNextGenerationA()
  546.  
  547.     SYNOPSIS
  548.         err = XarNextGenerationA( tags )
  549.         D0                         A0
  550.  
  551.         LONG XarNextGenerationA(struct TagItem *)
  552.  
  553.     FUNCTION
  554.         Unlike most other archivers xpkarchive supports filegenerations.
  555.         This feature allows to have more than one file with the same name in
  556.         one archive. In most cases this will be different versions of the
  557.         same file. It is thought that the newest version has the lowest
  558.         versionnumber. This function is used to increase the generation-
  559.         number of this file and all files with the same name and a higher
  560.         generationnumber. This function is automatically called by the
  561.         functions XarAddFile(),XarRenameFileA() and XarCopyFileA() to
  562.         prevent the duplicate occurrence of files with the same filename and
  563.         generationnumber. If you want to set the generationnumber of a single
  564.         file use the function XarModifyFileData().
  565.  
  566.     TAGS
  567.         supported tags:
  568.             XAR_Error
  569.             XAR_ArcLock
  570.             XAR_Archive
  571.             XAR_FileIndex
  572.             XAR_FileName
  573.             XAR_Generation
  574.  
  575.  
  576.     INPUT
  577.         tags    - Pointer to an array of struct TagItem. See xpkarchive/tags
  578.  
  579.     RESULT
  580.         err - Error code
  581.  
  582.     SEE ALSO
  583.         XarAddFile(), XarCopyFile(), XarRenameFileA(), XarModifyFileData(),
  584.         --generations--
  585.  
  586.  
  587. xpkarchive.library/XarNextLock                xpkarchive.library/XarNextLock
  588.  
  589.     NAME
  590.         XarNextLock()
  591.  
  592.     SYNOPSIS
  593.         arclock = XarNextLock( arclock )
  594.           D0                      A0
  595.  
  596.         XarLock * XarNextLock ( XarLock * )
  597.  
  598.     FUNCTION
  599.         Get the next entry of the contents list.
  600.  
  601.     INPUT
  602.         arclock - The arclock of a file
  603.  
  604.     RESULT
  605.         arclock - The arclock of the next file in the archive or NULL, if
  606.                   there is no file left.
  607.  
  608.     SEE ALSO
  609.         XarPrevLock(), XarGetLock()
  610.  
  611.  
  612. xpkarchive.library/XarOpenArchiveA        xpkarchive.library/XarOpenArchiveA
  613.  
  614.     NAME
  615.         XarOpenArchiveA
  616.  
  617.     SYNOPSIS
  618.         arc = XarOpenArchiveA( tags )
  619.         D0                  A0
  620.  
  621.         XarHandle *XarOpenArchiveA(struct TagItem *)
  622.  
  623.     FUNCTION
  624.         Opens an archive from disk and scans through the archive for
  625.         building the table of contents of the archive. You can access this
  626.         list using XarGetLock() to get the first entry and XarNextLock()/
  627.         XarPrevLock() to get the next/previous entry. XarOpenArchiveA() will
  628.         even recognize every CDAF-Archive e.g. archives that were generated
  629.         with shrink. You cannot add to or extract files from these archives,
  630.         but you can examine the contents of these archives with XarGetLock().
  631.  
  632.     INPUT
  633.         tags    - XAR_ArchiveName: The filename of the archive
  634.  
  635.                   XAR_ArchiveMode:
  636.                      There are three modes to open an archive:
  637.                         XAR_ModeOldArchive:
  638.                               Only existing archives will be opened. If it
  639.                               does not exist XarOpenArchiveA will fail. This
  640.                               is the default mode.
  641.                         XAR_ModeNewArchive:
  642.                               Existing files will be deleted and a new, empty
  643.                               archive will be created.
  644.                         XAR_ModeAppend:
  645.                               Creates an archive if none exists and opens the
  646.                               archive if one exists.
  647.  
  648.                 - See also xpkarchive/tags
  649.  
  650.     RESULT
  651.       XarHandle * if successful NULL else
  652.  
  653.     SEE ALSO
  654.       XarCloseArchive(),XarGetLock()
  655.  
  656.  
  657. xpkarchive.library/XarPrevLock                xpkarchive.library/XarNextLock
  658.  
  659.     NAME
  660.         XarPrevLock()
  661.  
  662.     SYNOPSIS
  663.         arclock = XarPrevLock( arclock )
  664.           D0                      A0
  665.  
  666.         XarLock * XarPrevLock ( XarLock * )
  667.  
  668.     FUNCTION
  669.         Get the previous entry of the contents list.
  670.  
  671.     INPUT
  672.         arclock - The arclock of a file
  673.  
  674.     RESULT
  675.         arclock - The arclock of the previous file in the archive or NULL,
  676.                   if there is no file left.
  677.  
  678.     SEE ALSO
  679.         XarNextLock(), XarGetLock()
  680.  
  681.  
  682. xpkarchive.library/XarRenameFileA          xpkarchive.library/XarRenameFileA
  683.  
  684.     NAME
  685.         XarRenameFileA()
  686.  
  687.     SYNOPSIS
  688.         err = XarRenameFileA( tags )
  689.         D0                     A0
  690.  
  691.         LONG XarRenameFileA(struct TagItem *)
  692.  
  693.     FUNCTION
  694.         In archives of the type "XPKArchive" it is possible to rename files.
  695.         Using this function you can set a new filename and generationnumber.
  696.         Internally it calls XarNextGeneration() to prevent duplicate
  697.         filenames with the same generationnumber by default. You can suppress
  698.         this by using the tag XAR_AutoNextGen.
  699.  
  700.     TAGS
  701.         supported tags:
  702.             XAR_ArcLock
  703.             XAR_Archive
  704.             XAR_FileIndex
  705.             XAR_FileName
  706.             XAR_Generation
  707.             XAR_Error
  708.             XAR_NewName
  709.             XAR_NewGeneration
  710.             XAR_AutoNextGen
  711.  
  712.     INPUT
  713.         tags    - Pointer to an array of struct TagItem. See xpkarchive/tags
  714.  
  715.     RESULT
  716.         err - Error code
  717.  
  718.     SEE ALSO
  719.         XarNextGeneration(),XarModifyFileData(), XarGetType()
  720.  
  721.  
  722. xpkarchive.library/XarSetFileNoteA        xpkarchive.library/XarSetFileNoteA
  723.  
  724.     NAME
  725.         XarSetFileNoteA()
  726.  
  727.     SYNOPSIS
  728.         err = XarSetFileNoteA( tags )
  729.         D0                      A0
  730.  
  731.         LONG XarSetFileNoteA(struct TagItem *)
  732.  
  733.     FUNCTION
  734.         In archives of the type "XPKArchive" it is possible to set filenotes
  735.         to files which are already in the archive. For removing filenotes
  736.         supply a pointer to a string of length 0 or a NULL-pointer.
  737.  
  738.     TAGS
  739.         supported tags:
  740.             XAR_Error
  741.             XAR_ArcLock
  742.             XAR_Archive
  743.             XAR_FileIndex
  744.             XAR_FileName
  745.             XAR_Generation
  746.             XAR_FileNote
  747.  
  748.     INPUT
  749.         tags    - Pointer to an array of struct TagItem. See xpkarchive/tags
  750.  
  751.     RESULT
  752.         err - Error code
  753.  
  754.     SEE ALSO
  755.         XarGetType()
  756.  
  757.  
  758. xpkarchive.library/--tags--                      xpkarchive.library/--tags--
  759.  
  760.     Tags for XarOpenArchiveA()
  761.  
  762.         XAR_ArchiveName  (UBYTE *)
  763.             Name of the file of the archive.
  764.  
  765.         XAR_ArchiveMode (ULONG)
  766.            There are three modes to open an archive:
  767.                 XAR_ModeOldArchive:
  768.                     Only existing archives will be opened. If it
  769.                     does not exist XarOpenArchiveA() will fail. This is
  770.                     the default mode.
  771.                 XAR_ModeNewArchive:
  772.                     Existing files will be deleted and a new, empty
  773.                     archive will be created.
  774.                 XAR_ModeAppen:
  775.                     Creates an archive if none exists and opens the
  776.                     archive if one exists.
  777.  
  778.  
  779.  
  780.  
  781.     Tags for all functions requiring tags except XarOpenArchiveA():
  782.  
  783.         XAR_ArcLock (XarLock *)
  784.             Arclock of the file.
  785.  
  786.         XAR_Archive (XarHandle *)
  787.             Archandle of the archive.
  788.  
  789.         XAR_FileIndex (ULONG)
  790.             Index of the file in the archive. This tag is only valid if
  791.             there is also XAR_Archive given.
  792.  
  793.         XAR_FileName (UBYTE *)
  794.             Filename of the file in the archive. This tag is only valid if
  795.             there is also XAR_Archive given. The default generation
  796.             is 0 unless you change the generation with the tag:
  797.  
  798.         XAR_Generation (UBYTE)
  799.             Generationnumber of the file in the archive.
  800.  
  801.  
  802.           For identifying file in the archive use one of the following:
  803.              - XAR_ArcLock
  804.           or - XAR_Archive + XAR_FileIndex
  805.           or - XAR_Archive + XAR_FileName  [ + XAR_Generation (default: 0)]
  806.  
  807.     NOTE: the combination of XAR_Archive and XAR_Filename is ambigous when
  808.           there is more than one file with the same filename and generation-
  809.           number in the archive. In this case it identifies the first file
  810.           in the archive that matches the filename and generationnumber.
  811.  
  812.  
  813.     Additional Tags for XarAddFileA():
  814.  
  815.         XAR_Archive,XAR_FileName,XAR_Generation,
  816.  
  817.         XAR_FileNote
  818.  
  819.         XAR_CRC
  820.  
  821.         XAR_Protection
  822.  
  823.         XAR_AutoNextGen
  824.  
  825.         XAR_TimeDay   (UBYTE)
  826.         XAR_TimeMonth (UBYTE)
  827.         XAR_TimeYear  (UBYTE)
  828.         XAR_TimeHour  (UBYTE)
  829.         XAR_TimeMin   (UBYTE)
  830.         XAR_TimeSec   (UBYTE)
  831.  
  832.         XAR_DateStamp (struct DateStamp *)
  833.             These tags are used to specify the time for XarAddFile() as
  834.             day, month, year, hour, minute and second or using a datestamp.
  835.             The default behaviour is to use the date and time of the file,
  836.             or in the case of XPK_InBuf or XPK_InHook the actual time.
  837.             This time can be altered using the above tags.
  838.  
  839.             These tags are also used to modify the FileData using
  840.             XarModifyFileData().
  841.  
  842.         XAR_CurrentTime (BOOLEAN)
  843.             Use the current time instead of the date and time of the file.
  844.  
  845.  
  846.  
  847.  
  848.     Additional Tags for XarRenameFileA()
  849.  
  850.         XAR_NewName (UBYTE *)
  851.             The new filename for the file.
  852.  
  853.         XAR_NewGeneration (UBYTE)
  854.             The new generationnumber for the file.
  855.  
  856.         XAR_AutoNextGen (ULONG)
  857.             Call XarNextGeneration if 1,which is the default value.
  858.             If you supply 0 then XarNextGeneration is not called. This may
  859.             result in duplicate files with the same generationnumber in the
  860.             archive.
  861.             IMPORTANT: You must not use other values than 0 or 1,
  862.             since it might be that there are other values with other
  863.             functionality in the future.
  864.  
  865.  
  866.  
  867.  
  868.     Additional tags for XarSetFileNoteA()
  869.  
  870.         XAR_FileNote (UBYTE *)
  871.             Filenote for the file. In the archive the filenotes have no
  872.             limited size, but remember that it is not possible to extract
  873.             the complete filenote, if it is longer than 80 bytes.
  874.  
  875.  
  876.  
  877.     Additional tags for XarCopyFileA()
  878.  
  879.         XAR_DestArchive (XarHandle *)
  880.             ArcHandle of the destination archive.
  881.  
  882.         XAR_AutoNextGen (ULONG)
  883.             (see above)
  884.  
  885.         XAR_NewName (UBYTE *)
  886.             New name for the file in the dest. archive,
  887.             default: use old name
  888.  
  889.         XAR_NewGeneration (UBYTE)
  890.             New generationnumber for the file in the dest. archive,
  891.             default: use old generationnumber
  892.  
  893.         XAR_FileNote (UBYTE *)
  894.             New filenote, default: use old filenote
  895.  
  896.  
  897.     Additional tags for XarModifyFileDataA() and XarAddFileA()
  898.  
  899.         XAR_CRC  (USHORT)
  900.             CRC checksums of the file in the archive. CRC checksums are not
  901.             supportet by the xpkarchive.library yet. With this option you
  902.             can add your own CRC Checksum to the file. The default value
  903.             used by xpkarchive.library is 0x00.
  904.  
  905.         XAR_Protection (ULONG)
  906.             Protection of the file.
  907.  
  908.         XAR_AutoNextGen (ULONG)
  909.             (see above)
  910.  
  911.  
  912.     Additional tags for XarOpenArchiveA()
  913.  
  914.         XAR_ArchiveMode (ULONG)
  915.             Mode of opening the archive. There are three modes to open the
  916.             archive:
  917.  
  918.                 XAR_ModeOldArchive:
  919.                     Only existing archives will be opened. If it does not
  920.                     exist XarOpenArchiveA() will fail. This is the default
  921.                     mode.
  922.  
  923.                 XAR_ModeNewArchive:
  924.                     Existing files will be deleted and a new, empty archive
  925.                     will be created.
  926.  
  927.                 XAR_ModeAppend:
  928.                     Creates an archive if none exists and opens the archive
  929.                     if one exists.
  930.  
  931.  
  932.     Global tags for all functions
  933.  
  934.         XAR_Error (LONG *)
  935.             Pointer to an error variable. The error code is stored in this
  936.             variable on failure. Error codes <0 are error codes of the
  937.             xpkmaster.library (see xpk.h), error codes >0 are from the
  938.             xpkarchive.library.
  939.         IMPORTANT NOTE:
  940.             Only error-codes >=XARERROR_LEVEL are real errors. The other
  941.             codes are just informational or warnings. See also --Error--
  942.  
  943.  
  944.     Input / Output tags:
  945.  
  946.         The normal xpk-tags from xpkmaster.library are used as input/output
  947.         tags. Be aware that you must not supply ouput tags to XarAddFileA()
  948.         and no input tags to XarExtractFileA().
  949.  
  950. xpkarchive.library/--error--                    xpkarchive.library/--error--
  951.  
  952.     Some notes about the error codes:
  953.  
  954.     The xpkarchive.library has three levels of error codes:
  955.  
  956.         - Informational codes: These are no errors at all.
  957.  
  958.             XARINF_NEW_ARCHIVE:     A new archive has been created.
  959.             XARINF_NOT_EXCLUSIVE:   The archivefile could not be opened for
  960.                                     exclusive access. This will lead to
  961.                                     corrupted archives, if an archive is
  962.                                     opened more than once and data is
  963.                                     written to it.
  964.                                     For V36 or higher the archive is opened
  965.                                     using an exclusive Lock and
  966.                                     OpenFromLock();
  967.             XARINF_ARCHIVE_CORRUPT: There are more or less harmless errors
  968.                                     in the archive.
  969.  
  970.         - Warning codes (code>=XARWARNING_LEVEL): They give you a warning
  971.             that there is something wrong with the archive.
  972.  
  973.             XARWARN_ARCHIVE_CORRUPT: There is a serious error in the
  974.                 archive. Therefore it is not possible to add any files to
  975.                 the archive any more. If you try it you will get the error
  976.                 code XARERR_ARCHIVE_CORRUPT. You can still try to extract
  977.                 files from the archive.
  978.  
  979.             For the other codes read xpkarchive.h
  980.  
  981.         - Error codes (code>=XARERROR_LEVEL): Real error codes
  982.  
  983. xpkarchive.library/--generations--        xpkarchive.library/--generations--
  984.  
  985.    Unlike most formats of other archivers the file-format that is used by
  986.    the xpkarchive.library supports having different versions of one file
  987.    with the same filename in one archive. Therefore this file-format
  988.    supports generations of files, which identify different versions of the
  989.    file. The lower the generationnumber the newer is the file. Since it is
  990.    always possible to modify the generationnumber by the programmer it may
  991.    occur that there are files with the same filename and generation.
  992.    It is the job of the programmer to prevent duplicate generationnmbers of
  993.    one file except for the special generationnumber XAR_FileDeleted.
  994.    Deleted files are not removed from the archive. The only way to get rid
  995.    of these files is to generate a new archive and copy the files, which are
  996.    not deleted or which have a generationnumber lower than a certain level
  997.    to this archive and delete the old archive.
  998.  
  999.  
  1000. xpkarchive.library/--BUGS--
  1001.  
  1002.    The xpkarchive.library does not support the tags TAG_MORE and TAG_SKIP
  1003.    yet.
  1004.  
  1005.  
  1006.  
  1007.  
  1008.